Selecting and Paying Tolls (C++)

This topic applies to Windows XP Home Edition and Windows XP Professional only.

When a policy creates a denial and its associated tolls, the application must display them and enable the user to select tolls for payment. When you design the application's UI, consider the following points:

• To unblock the request, the user must resolve every denial.
• For each denial, it is sufficient to pay one toll to resolve the denial.
• If a toll has secondary denials, the user must resolve all of them before paying the toll.
• The denial/toll tree is arbitrarily deep.

When a policy adds a toll to a denial, the CA Manager fires an _ICAManagerEvents::DenialTollAdded event. If a policy adds a secondary denial to a toll, the CA Manager fires an _ICAManagerEvents::TollDenialAdded event. It also fires events when a policy removes a toll or a denial. The application can use these events to keep its UI updated.

The user might need to resolve several denials, so toll payment happens in two stages:

1. Select which tolls to pay by calling the ICAToll::Select method. This method sets the toll's state to Selected, unselects any other tolls in the same collection, and triggers an _ICAManagerEvents::TollStateChanged event.
2. Retrieve the denials collection on the request and call the ICADenials::PaySelectedTolls method. This method traverses the denial/toll tree, depth first, and calls the ICAToll::PayToll method on every toll that is both selected and not blocked by a denial. Each toll implements its own PayToll method, possibly with its own UI, such as a dialog box.

In a typical application, the user will initiate these actions. For example, the application might call Select when the user clicks on a toll, and call PaySelectedTolls when the user clicks a "Pay Tolls" button. Call the ICADenials::get_CountSelected method to determine whether the user has selected enough tolls to unblock the request.

The following example shows an outline of what to do. The details will depend on your application's UI.

// Event handler for the toll-added event.
void __stdcall OnTollDenied(ICADenial *pDenial, ICAToll *pToll, long cCount)
{
    CComBSTR bstrDesc;
    pToll->get_Description(Short, &bstrDesc);
    UpdateUISomehow(bstrDesc);
}

// The user selected a toll.
void UserSelectedSomeToll(ICAToll *pToll)
{
    CComPtr<ICARequest> pReq;
    CComPtr<ICADenials> pDenials;
    long cSelected;

    // Select the toll object.
    pToll->Select(TRUE);

    // Are enough tolls selected to resolve the denial?
    m_pCAManager->get_ActiveRequest(&pReq);
    pReq->get_Denials(&pDenials);
    pDenials->get_CountSelected(&cSelected);
    if (cSelected > 0)
    {
        // Enable a "Pay Tolls" button. 
        EnableWindow(GetDlgItem(m_hwnd, IDC_PAYTOLL), TRUE);
    }
}

// The user wants to pay the selected tolls.
void OnPayTollsClick()
{
    CComPtr<ICARequest> pReq;
    CComPtr<ICADenials> pDenials;
    m_pCAManager->get_ActiveRequest(&pReq);
    pReq->get_Denials(&pDenials);
    pDenials->PaySelectedTolls();
}

Refunding Paid Tolls

The CA Manager keeps a collection of paid tolls. Whenever the user pays a toll, the owning policy copies that toll into the collection. The toll's ICAToll::get_Refundable method indicates whether the user can obtain a refund for the toll. The value depends on the implementation of the toll and the owning policy. If the toll is refundable, you can refund it by calling the ICAToll::RefundToll method.